<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" type="text/css" href="doc.css" />
<title>Transaction Options</title>
</head>
<body>
<h1><a name="top">Transaction Options</a></h1>
<p>
</p>

The
<a href="../javadoc/org/eclipse/emf/transaction/TransactionalCommandStack.html"><em class="CodeName">TransactionalCommandStack.execute()</em></a>
method accepts a map of options defined by the
<a href="../javadoc/org/eclipse/emf/transaction/Transaction.html"><em class="CodeName">Transaction</em></a>
interface that determine how changes occurring during the transaction are handled:
<ul>
  <li><em class="CodeName">OPTION_NO_NOTIFICATIONS</em>: changes are not included in
      post-commit change events, so they are not sent to <a href="listeners.html">listeners</a></li>
  <li><em class="CodeName">OPTION_NO_TRIGGERS</em>: changes are not included in pre-commit
      change events, so they are not sent to <a href="triggers.html">triggers</a></li>
  <li><em class="CodeName">OPTION_NO_VALIDATION</em>: changes are not validated</li>
  <li><em class="CodeName">OPTION_NO_UNDO</em>:  changes are not recorded for undo/redo
      and rollback.  Use with extreme caution</li>
  <li><em class="CodeName">OPTION_UNPROTECTED</em>: implies <em class="CodeName">OPTION_NO_UNDO</em>,
      <em class="CodeName">OPTION_NO_VALIDATION</em>, and <em class="CodeName">OPTION_NO_TRIGGERS</em>.
      In addition, permits writing to the resource set even in an otherwise read-only
      context.  Use with even more extreme caution.  There are almost no situations in
      which this is a safe or reasonable option to apply to a transaction.  Exceptions are
      cases where the transaction is updating objects that no other transaction in any
      other thread could yet have observed.</li>
</ul>
<p>
These options are all boolean-valued.  They all default to <em class="CodeName">false</em>.
</p>

<blockquote>
	<img src="images/options.png" alt="Transaction Options"/><br/>
	<font size="-2">[<a href="images/options.svg">as SVG</a>]</font>
</blockquote>

<p>
Another option, <em class="CodeName">OPTION_IS_UNDO_REDO_TRANSACTION</em> is merely
informative.  It is applied by the transaction API, itself, to indicate to clients that
a transaction's changes result from undo or redo of a <em class="CodeName">Command</em>.
<a href="listeners.html">Listeners</a>, on receiving notification of changes in the resource
set, can look for this option if they need to distinguish between changes that occurred
in the original execution of a command versus undo or redo of a command.  It would be
highly unual for a client of the transaction API to apply this option.
</p>
<pre class="Code">
TransactionalCommandStack stack;
Library library;

// don't tell the UI that we are changing the library name
stack.execute(
    SetCommand.create(domain, library,
        EXTLibraryPackage.Literals.LIBRARY__NAME, "Secret Name"),
    Collections.<b>singletonMap</b>(
            Transaction.<b>OPTION_NO_NOTIFICATIONS</b>, Boolean.TRUE));
</pre>
<p>
Most of these options apply only to read/write transactions.  They have no effect on
read-only transactions, except only the <em class="CodeName">OPTION_NO_NOTIFICATIONS</em>.
Reading the resource set can cause such changes as proxy resolution and resource loading,
which generate change events, although they do not indicate changes to the abstract state
of the data.
</p>

<p>
The <em class="CodeName">TransactionalCommandStack</em> implementations of the
<em class="CodeName">undo()</em> and <em class="CodeName">redo()</em> methods use the
following options for the transactions created for undo and redo of commands:
</p>
<ul>
  <li><em class="CodeName">OPTION_NO_UNDO</em>:  because we are undoing or redoing a
      command whose changes we have already recorded, there is no need to record anew</li>
  <li><em class="CodeName">OPTION_NO_TRIGGERS</em>:  triggers performed during execution
      were recorded and are automatically undone; any additional changes would be
      inappropriate</li>
  <li><em class="CodeName">OPTION_NO_VALIDATION</em>:  there is no need to validate a
      reversion to a previous state of the data</li>
  <li><em class="CodeName">OPTION_IS_UNDO_REDO_TRANSACTION</em>:  the transaction's changes
      are simply undoing or redoing changes made previously</li>
</ul>

<hr/>

<p>
<a href="https://www.eclipse.org/legal/epl-2.0/">Copyright (c) 2006, 2007 IBM Corporation and others.</a>
</p>
</body>
</html>
